home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 4 / United Public Domain Gold 4.iso / scope / sc093.dms / sc093.adf / WBRes / wbres.doc < prev    next >
Text File  |  1989-12-14  |  16KB  |  323 lines
  1.                              WBRes Documentation 
  2.  
  3. Program: WBRes 1.1.
  4.  
  5. Purpose: To allow WB users to have "resident" programs. As in the resident
  6.     capability of WShell, AShell, and the WB1.3 Shell. WBRes came into
  7.     being at the tail end of a failed attempt to do (on a single-program
  8.     scale) the same thing for ty. The original problem was how to reduce
  9.     the time required to load to load ty when reading a text file on the
  10.     NZAmigaUG Newsdisks, which are bootable, and boot into the WB
  11.     environment. Hence the Autoicon and CLI arg features, for use in a
  12.     startup script.
  13.  
  14. Author:  John Bickers (JJB TEMPLAR),
  15.          214 Rata St,
  16.          Naenae 6301,
  17.          New Zealand.
  18.  
  19. Usage:
  20.  
  21.                         ----- Starting WBRes -----
  22.  
  23.     WBRes can be started from either CLI or Workbench. Some of the possible
  24.     errors that can occur at this point are:
  25.     Someone's got the DOS "vectors"!
  26.         WBRes has to intercept the AmigaDOS functions "LoadSeg" and
  27.         "UnLoadSeg". The method involved creates a lot of problems (partly
  28.         because of the format of the DOS "vector" table) if the vectors
  29.         have already been intercepted, and/or WBRes or other interceptors
  30.         are allowed to terminate. This is also how WBRes tells whether or
  31.         not it is already present in the system.
  32.     Workbench isn't there!
  33.         WBRes requires the Workbench task to have been started before WBRes
  34.         installs itself. If it hasn't been loaded, then there is no point
  35.         in running WBRes anyway.
  36.  
  37.     These errors are not reported if the program was started from the WB.
  38.     So to determine what's going on, try starting WBRes from a CLI.
  39.  
  40.     CLI arguments:
  41.     The format is:      WBRes [<-opt>] [<file>]
  42.         where [] means optional, <> means 1 or more.
  43.     The options are:
  44.         '?'     : Give a brief help message.
  45.         'I'     : Set Autoicon flag to ON.
  46.         'a'     : Toggle the state of the "active" flag when loading
  47.             programs from the following CLI argument list. This flag starts
  48.             in the ON position. For example, entering:
  49.                 1> WBRes c:ty -a c:more -a c:display
  50.             will load the programs as follows:
  51.                         ty:         active
  52.                         more:       inactive
  53.                         display:    active
  54.         'i'     : Toggle the state of the "ignore checksum" mode. Works in
  55.             the same way as the 'a' flag, but starts in the OFF position.
  56.  
  57.     WB arguments:
  58.     These are contained in the ToolTypes array of the WBRes icon. In order
  59.     to scan for arbitrary filenames, these do not work exactly like they
  60.     normally do. So if you plan to use these arguments, please take note.
  61.     The icon is NOT checked if WBRes was started from the CLI.
  62.  
  63.     The ToolType entries are understood as follows:
  64.         ICONIFY=ON .............. This literal string sets Autoicon to ON.
  65.         [*[<a|i| >]=]filename ... This specifies "filename" as a file to be
  66.             loaded by WBRes. The optional modes string allows you to
  67.             specify the state of the "active" and "ignore checksum" flags
  68.             when loading. The default states for each file are active = on,
  69.             ignore checksum = off.
  70.  
  71.     The following (between "") are example lines from the ToolTypes array.
  72.  
  73.     ×»  "ICONIFY=ON"
  74.         Sets Autoicon to ON. Note that ICONIFY=OFF is NOT the reverse.
  75.  
  76.     ×»  "AmigaLibDisk230:Fedup/Fedup"
  77.         This would load Fedup, from the disk AmigaLibDisk230.
  78.  
  79.     ×»  "*ai=AmigaLibDisk230:Fedup/Fedup"
  80.         This would load Fedup, but with the active mode off, and the ignore
  81.         checksum mode on.
  82.  
  83.     ×»  "*aia i=My Boot Disk:c/more"
  84.         This would load more. Note that the redundant flags in the modes
  85.         string have no effect. They do NOT act as toggles.
  86.  
  87.  
  88.                          ----- The display -----
  89.  
  90.     The resident list is displayed in the grey square to the left. Use
  91.     the scroll bar, arrow gadgets, or up/down keys to move up and down the
  92.     list if it is too long to be displayed all at once.
  93.  
  94.     The current command, if there is one, is shown in the black rectangle
  95.     in the lower right. Above this rectangle are the main control Gadgets.
  96.  
  97.     The format of an entry in the display list indicates the state of the
  98.     program for that entry (or node).
  99.         A white circle filled with red means this node is "active".
  100.         An empty white circle means this node is not "active".
  101.         A small x means this node has a bad checksum.
  102.         Red text means you want the checksum ignored for this node.
  103.         A name without a usage count, no small image, and a name in
  104.             brackets following it, means this node is an alias.
  105.     The 3 digits to the right are the lower 3 decimal digits of the usage
  106.     count that is kept for that program.
  107.  
  108.     Whenever the main window is opened, the current Workbench colors are
  109.     saved, and WBRes' palette is loaded. There is a reason for this, which
  110.     I'll get to. When the window is closed (ie: terminating, or Iconifying)
  111.     the old colors are put back. I'll use Preferences to do this when it
  112.     becomes necessary (WB1.4?).
  113.  
  114.     Now the reason. When adding gadgets to ty, I come in for some criticism
  115.     to do with how the gadgets looked when certain unsensible people used
  116.     certain unsensible color schemes for their Preferences. By unsensible I
  117.     mean colors that didn't match mine! Shadowed text was the worst
  118.     affected, but my small (also shadowed) gadgets were pretty bad too. So
  119.     WBRes sets the colors to what I use. And since I expect it to be
  120.     Iconified most of the time, that's OK. Just endure my colors while
  121.     actually using my program.
  122.  
  123.     Most gadgets, etc, use the topaz 8 font where I was able to get them
  124.     to. However, the window title is not changed, and the font used in the
  125.     string requester is not changed. They will be, as soon as I figure out
  126.     how to accomplish it. The point of worrying about what fonts are being
  127.     used is that some people do regularly use strange fonts, and programs
  128.     that don't take account of this do not look nice.
  129.  
  130.  
  131.                           ----- Operations -----
  132.  
  133.     Some operations require a "current node" to be selected. To do this,
  134.     click on the name of a program in the displayed resident list. If no
  135.     programs are displayed, then load one/some.
  136.  
  137.     Load ...... This loads a command. A simple string gadget is used. If or
  138.         when I get the docs for the ARP requester, I will use that too.
  139.         Though I'd prefer it if CBM put RJMical's requester into the system
  140.         somewhere (with hooks to change the gadget imagery?), since the
  141.         ARP requester re-reads the disk every time it's visited, and
  142.         updates the file list in a silly way. For great design, see RJM's,
  143.         on Fish107.
  144.  
  145.     Delete .... This removes the current program from the resident list. It
  146.         requires you to verify the deletion. A reason this may not work is
  147.         that the current program has an invocation running. In this case it
  148.         would not be safe to remove it from the list. Actually, it is safe,
  149.         but there are problems.
  150.  
  151.         If you delete an alias, only the alias node will be removed. If you
  152.         delete a node that has aliases bound to it, all the aliases will be
  153.         deleted too.
  154.  
  155.     Pick ...... Clicking on a program name in the list display will make
  156.         that program the current node. This must be used before the node-
  157.         specific operations, like "Delete", etc.
  158.  
  159.     Activate .. Clicking on the white circle at the left of a program name
  160.         in the display list will toggle that node's "active" state. If a
  161.         program is not active, then the resident copy of the program will
  162.         be bypassed. An active node is indicated by a white circle filled
  163.         with red.
  164.  
  165.     Ignore .... This toggles a flag telling WBRes to ignore the checksum
  166.         used to verify a program's purity. This is based on the way WHawes'
  167.         "resi" command does things. It is necessary for programs like CBM's
  168.         "more", which work as resident programs, but do get a bad checksum
  169.         error. Programs with this flag ON are drawn as red, with no shadow.
  170.  
  171.     Rename .... Rename the current node. The new name can be up to 30-odd
  172.         characters, a little bit more than DOS itself allows, though that
  173.         wouldn't generally be useful to you. You are not allowed to use
  174.         names already present on the list. There are reasons for using this
  175.         as well as having an "Alias" operation, like renaming aliases.
  176.  
  177.     Alias ..... Define an alias for the current node. You are not allowed
  178.         to use names already present on the list. If the current node
  179.         itself is an alias, then the new alias is bound onto the real node
  180.         that the current node is bound to. So the aliases are only one
  181.         level deep. Note that only programs loaded into WBRes can have
  182.         aliases. A general Workbench alias capability can be added, but
  183.         only if demand is great enough.
  184.  
  185.         As to why there is an alias command, a good example is PD disks and
  186.         text display programs. My second favorite (next to "more v3.23"),
  187.         and the one I use from WB, is "ty1.3". This is primarily due to the
  188.         fact that I had a hand in writing it. Anyway, it is not used on any
  189.         PD disks other than the NZAmigaUG's. So by loading it into WBRes,
  190.         then defining a series of aliases, like "more" (AMICUS & TBAG),
  191.         "most" (AmigaTECH), "PrinText" (AmsMag), "QView" (Amigan), "Less"
  192.         and "Muchmore" (AmigaLibDisks), etc, I can browse through text
  193.         files with a single text reader.
  194.  
  195.     Iconify ... This makes WBRes Iconify. Leo Schwab's excellent Iconify
  196.         function from Fish126 is used for this. To de-iconify the program,
  197.         double-click on the small image.
  198.  
  199.     Help....... This displays a few fairly meagre help "screen"s.
  200.  
  201.     Quit ...... Will terminate WBRes. It will not terminate if there are
  202.         any programs on the list that have a current invocation running.
  203.         Any commands not running will be deleted, as will all aliases.
  204.  
  205.  
  206.                            ----- Controls -----
  207.  
  208.     By operation, the controls are:
  209.         Load ...... LOAD gadget, or press 'L'.
  210.         Delete .... DELETE gadget, or press 'DEL'.
  211.         Pick ...... Explained above.
  212.         Activate .. Explained above.
  213.         Ignore .... IGNORE gadget, or press 'I'.
  214.         Rename .... Press 'R'.
  215.         Alias ..... Press 'A'.
  216.         Iconify ... ICON gadget, or press 'F1' (as in Conman).
  217.         Help ...... HELP gadget, or press 'HELP'.
  218.         Quit ...... QUIT gadget, close window, or press 'ESC'.
  219.  
  220.     In addition, you can "next-page" the help displays by pressing 'SPACE',
  221.     and use the arrow keys, scroll bar, or arrow gadgets to move up and
  222.     down within the display list.
  223.  
  224.     The JJB/TEMPLAR gadget is my semi-active logo, and doesn't do much.
  225.  
  226.  
  227.                           ----- The future -----
  228.  
  229.     Depending on the demand, and the availability of documentation, I would
  230.     like to add (at least) the following:
  231.  
  232.     ×»  Scanning WShell's resident list. And CBM's and ARP's if possible.
  233.         Also, if it doesn't make WBRes redundant, I'll update it to handle
  234.         Workbench 1.4. I can, if there's any demand for it, get WShell to
  235.         make use of my list using the method outlined in Appendix B of "The
  236.         Beachcomber's Guide to the WShell". Also, if I do get to use the
  237.         WShell resident list, then I won't do CBM's or ARP's. Almost
  238.         everyone should buy WShell anyway, to make up for not paying the
  239.         shareware on Conman.
  240.  
  241.     ×»  Using a "real" file requester.
  242.  
  243.     ×»  Alias specifications as arguments.
  244.  
  245.     ×»  And ENV: or S: argument capability (probably S:, as it'll be multi-
  246.         line).
  247.  
  248.  
  249.                         ----- Known problems -----
  250.  
  251.     There are several "critical" sections in this program, that I have not
  252.     protected. In practice it appears they zip by too fast for the user to
  253.     be able to cause a GURU, but if there are problems I'll add the protect
  254.     code. I'd like to evaluate the necessity for it first.
  255.  
  256.     Intercepting the DOS functions was not a happy task. I make one or two
  257.     assumptions about the format of the DOS library that may break with
  258.     KS1.3 or higher. Let me know.
  259.  
  260.     WB1.4 has been rumored to multitask. This may cause a problem, if the
  261.     "Workbench" task is not the one that calls LoadSeg for Workbench. But
  262.     then CBM may have a WB resident capability of their own, so there won't
  263.     be any need for WBRes.
  264.  
  265. Distribution:
  266.     This program is almost freely redistributable. That is, anyone may
  267.     distribute it provided the following requirements are met:
  268.  
  269.     1)  This documentation file accompanies it.
  270.     2)  The distribution is non-commercial in nature, with the exception of
  271.         WHawes' WShell. AmigaLibDisk would be great, as would any other PD
  272.         disks. Non-PD disks, like DevDisk, are not.
  273.     3)  Neither WBRes nor this doc file are altered, other than for
  274.         archiving purposes (this means YOU, Tony! :-).
  275.     4)  It's understood that I accept no responsibility for any losses this
  276.         program may cause. It hasn't done anything bad on my machine, if
  277.         that's any consolation.
  278.  
  279.     While this program is freely redistributable, it is:
  280.  
  281.     1)  Copyright © 1989 by John Bickers.
  282.         Actually, this isn't formally registered anywhere, if that's
  283.         necessary, so perhaps it isn't. Oh well :-).
  284.     2)  Shareware. The amount is up to you. The obligation is entirely
  285.         moral, and only required if you use this program often.
  286.         Experimenting is free. Please note that I'm currently unemployed,
  287.         and have 104 children to feed, put through school, etc (**), so I
  288.         need every cent.
  289.     This is all negotiable, but with me, and probably at some cost.
  290.  
  291.     My "policy" on this shareware stuff is:
  292.  
  293.     1)  The top $5 is a contribution, and pays for registration.
  294.     2)  Every $5 after that is also a contribution, but pays for postage of
  295.         updates, etc, if there are any.
  296.     3)  The top $5 may be replaced by non-financial rewards like:
  297.             Used electronic music (eg: DEVO, Men Without Hats).
  298.             PD stuff.
  299.             Or whatever. As long as I won't be had up by the Customs Dept.
  300.     4)  Any problems/complaints will only be answered if the person
  301.         involved is a registered user, or one of the people named below.
  302.         IE: if I shake the envelope, and only a letter falls out, both go
  303.             into the dustbag (after I've secured the stamp :-).
  304.     5)  The actual funds may be in any legal currency. I was going to
  305.         specify $NZ drawn on an NZ bank, like the Yanks specify $US, but
  306.         thought better of it.
  307.  
  308.     The following people are exempt from the shareware burden:
  309.             Tony Wills,             Fred Fish,
  310.             Will Hawes,             Leo Schwab,
  311.     and past and present employees of CBM, or companies related to CBM.
  312.  
  313. Complaints/Suggestions/Questions:
  314.     Contact:-   John Bickers,
  315.                 214 Rata St,
  316.                 Naenae 6301,
  317.                 New Zealand.
  318.  
  319.     Phone:-     (04) 672-085.
  320.  
  321. **  The part about the kids is not actually true. But I do need to keep my
  322.     machine out of repossession.
  323.